Using Timestamps

A timestamp is a standard sequence of characters describing date and/or time. The format of the timestamp is consistent, and stores the date/time of an event occurrence (for example, alarm, file creation, modification, etc.).

CygNet stores data in Coordinated Universal Time (UTC). This is sometimes called Zulu (Z) or Greenwich Mean Time (GMT) elsewhere. Whereas input may be required in varying formats depending on the interface, CygNet stores the date/time uniformly. The basic format (YYYYMMDD for date and hhmmss for time) or extended format (YYYY-MM-DD for date and hh:mm:ss for time) are both used.

Time Zone

By default, a UIS is assumed to be in the same time zone as its connected field devices. If a field device is not in the same time zone as its associated UIS, you must specify the time zone of the field device in the Display Name drop-down menu of the Time Zone page in the remote device editor. Drop-down options are only available if you have properly defined and installed a CygNetTimeZones.xml file.

If a field device returns timestamps, the values are stored unaltered in the DDS. When a field device provides timestamps on historical data records, they are converted to UTC time by the UIS when performing point processing.

The scenarios below are provided to help you understand how the time would be displayed on different computers. In all three scenarios, a host (UIS) polls a field device for data at 09:00 Central Standard Time (CST) and stores the data with a timestamp of 15:00 UTC (also referred to as Greenwich Mean Time or GMT).

• Scenario 1: Two client computers are on CST. The timestamp on both would show as 09:00.

• Scenario 2: Client Computer #1 is on CST and client computer #2 is on Central Daylight Time (CDT). The timestamp on the client computer #1 shows 09:00. The timestamp on the client computer #2 shows 10:00. Both times are 15:00 GMT.

• Scenario 3: Client Computer #1 and client computer #2 are in different time zones — the client computer on CST would see a timestamp of 09:00. The client computer on Mountain Standard Time (MST) would see a timestamp of 08:00. Both times are 15:00 GMT.

Data Timestamped by an RTU

If an RTU timestamps data, that timestamp is retained and displayed in CygNet. This is generally the case for history-type data groups, plunger times, etc. The timestamp may be for the beginning of the period (leading) or the end of the period (trailing); either way, it is RTU-specific.

There are some history-type data groups that return an array of data but do not timestamp the values. For example, a data group that returns an average value for each hour. In such cases, the DDS editor presents the data on the hour for each hour (07:00, 08:00, 09:00). That is because each value is representative of an hour slot. Since the data didn’t come with a timestamp, CygNet writes the timestamp as the data is written to a point. Depending upon the EIE, the data may be timestamped on the hour (07:00, 08:00, 09:00) or mid-hour (07:30, 08:30, 09:30).

Contract Time

Contract time is an offset from the device time, in number of hours as defined by the contract hour property. It is determined by the hour at which the contract day begins. Contract time is an option in several areas of CygNet.

See Using Contract Hour in CygNet Measurement for more information about the use of Contract time (C) in CygNet Measurement.

XML-Based Schema

For applications utilizing XML-based schemas, the timestamps must be in dateTime format, and can be modified with a time zone offset. Energy Load Forecasting and Enterprise Objects are examples of CygNet operations based on XML schema.

When creating a data input file, you can specify the timestamp values in UTC time, or you can specify an offset from the UTC time. If the timestamp value does not specify either UTC time or a time zone offset, it is interpreted to be the local server time.

dateTime Format

Timestamps used in elements and attributes in CygNet data input files must be in dateTime data type format, which takes the following form.

YYYY-MM-DDThh:mm:ss

Optional forms include the following.

YYYY-MM-DDThh:mm:ss.s+

 

YYYY-MM-DDThh:mm:ssZ

 

YYYY-MM-DDThh:mm:sszzzzzz

Timestamp components represent the following values.

Component	Value
YYYY	The year (four digits)
-	A separator between parts of the date
MM	The month (two digits)
-	A separator between parts of the date
DD	The day (two digits)
T	A separator indicating that time-of-day follows
hh	The hour (must not be 24, unless both mm and ss are zero, and the first instant of the following day)
:	A separator between parts of the time
mm	The minutes
:	A separator between parts of the time
ss	The whole seconds
.s+	The fractional seconds (optional) Must not end in '0'
Z	Zero-length time zone: UTC time (optional)
zzzzzz	The time zone offset (optional) Example +03:00 See Time Zone Offset

Example

2023-09-10T12:00:00-05:00 (noon on 10 September 2023, Eastern Standard Time in the U.S.) is 2023-09-10T17:00:00Z, five hours later than 2023-09-10T12:00:00Z.

Input file examples are as follows.

<StartTime>2023-01-01T09:00:00.000Z</StartTime> <EndTime>2023-01-01T10:00:00.000Z</EndTime>

or

<start_time="2023-07-22T13:00:00.000Z" end_time="2023-07-22T14:00:00.000Z">

Time Zone Offset

To specify UTC time zone, you can enter a timestamp with "Z" added after the time. Or you can specify an offset from the UTC time by adding a positive or negative time adjustment after the time, represented by zzzzzz (for example, "+03:00"). Specifying an offset of "-00:00" or "+00:00" would therefore be the equivalent of specifying "Z" (UTC time).

The time zone offset takes the following form.

('+' | '-') hh ':' mm

where

Component	Represents
+ / -	'+' indicates a nonnegative duration '-' indicates a nonpositive duration
hh	The hours (two digits)
:	A separator between parts of the time
mm	The minutes (two digits)

When a time zone is added to a UTC dateTime, the result is the date and time "in that time zone."

Example

2023-10-10T12:00:00+05:00 is 2023-10-10T07:00:00Z

2023-10-10T00:00:00+05:00 is 2023-10-10T19:00:00Z

Input file examples are as follows.

<StartTime>2023-01-01T09:00:00.000-08:00</StartTime> <EndTime>2023-01-01T10:00:00.000-08:00</EndTime>

or

<start_time="2023-07-22T13:00:00.000-07:00" end_time="2023-07-22T14:00:00.000-07:00">